Add-On Script Tutorial
This tutorial covers how to edit, and add a tool to the game utilizing Add-On Scripts. __TOC__ Introduction The purpose of this tutorial is to give you (the user) a basic step-by-step process on how to edit and add your own tools to the add-on scripts so the 3D Mesh Replacements can be Additions instead (ex: it will no longer replace an item, it will instead appear as an additional item available for selection). This tutorial assumes the following: *You have zero knowledge with scripts *You have NotePad or WordPad *You have the tools necessary to decode and encode files (.bsb and .txx) In this tutorial all "Default 3DSV names" will be replaced with "TheGame". So for example, if I say create a folder called: TheGame.000.AddOnScript it really should be: 3DSV.000.AddOnScript (with 3DSV unabbreviated) File Nomenclature File Definitions / Type There are basically 4 types of file the game uses. They are: 1. Txx (example: TheGame.123.txx) *These are the files the game reads, they include all other type of files. These are found (and go) in your archives folder 2. BSB (example: tool09.bsb) or AcTool09.bsb) *These files may contain either mesh data, scripts or a mixture of both. They are found inside folders within Txx files. 3. Texture Files (example: tool09.png) *These files are generally the texture file associated with a mesh file (.png). Or they are small sized (128x128) files used for icons (.jp2) *Note: The game will always accept texture files in the format of .png, when in doubt, use .png format. 4. Txf (example tool09.txf) *These filles dictate transparency values, more information can be found on the game's wiki. These are always in the same folder as the texture files. Basic File Editing Summary #Decode Txx file #Find the bsb file(s) you want to edit #Decode the bsb file(s), Edit it, and save #Encode the bsb file(s) #Encode the txx file Getting Started First, download the latest (as of writing this tutorial) add-on tools pack here: http://www.putlocker.com/file/AADB7381B2E23CC5 Next, lets use a teddy bear mesh mod (replaces the carrot by default) as our sample tool add-on. Download it here: http://www.putlocker.com/file/AA587F64BDECE6AD Extract both the files on your desktop. You should have ended up with the following: TheGame.AA3.CuddlyTeddy.txx + a bear.png in the Teddy Bear Mod folder and TheGame.020.R9AddOnTools1.txx in the R9AddOnTools1_v1.5_tutorialversion folder Tool Settings Before we start editing, it is important that you have the following settings when you are decoding or encoding: For Txx Decoder / Encoder: For BSB decoder / encoder: Decoding Settings Encoding Settings The tutorial assumes you have these settings! Decoding Files First use the Txx Tool, click "process" go to select file, and select the TheGame.AA3.CuddlyTeddy.txx and hit decode. Repeat the above process, but this time select TheGame.020.R9AddOnTools1.txx instead. You should now have a folder where you decoded your .txx files. It should have the exact same name as the txx files (without the .txx) Now use the BSB tool and decode the following files: -- In the Teddy Bear Mod folder navigate to the items folder and decode the tool07.bsb: \Teddy Bear Mod\TheGame.AA3.CuddlyTeddy\Scenes\Shared\Item\'tool07.bsb' -- In the TheGame.020.R9AddOnTools1 folder navigate the the following folders and decode the file in bold: \TheGame.020.R9AddOnTools1\Scripts\Luder\Item\'AcTool30301.bsb' \TheGame.020.R9AddOnTools1\Scripts\Shared\GUI\'IconCollection_T1addonTools.bsb' \TheGame.020.R9AddOnTools1\Scripts\Shared\Common\ TcToolsAttributesT1Addon.bsb TcToolsT1Addon.bsb TcToolsT1Addon.L=EN.bsb Editing and Encoding Files Note: To edit anything, you must first decode the file. Afterwards, you must re-encode the file. So we have 2 major folders. One is the Teddy Bear Mod folder decoded, which contains the "Texture" and the "Mesh" file. The other folder contains the other add-ons, with their own individual Texture, and Mesh file. In addition there is also a script file that goes along with them. What we are going to do now is the following: Part A: 1. Move the texture file (for the icon and for the mesh itself) from the Teddy bear folder to the add-on folder. 2. Move and edit the mesh file from the Teddy Bear Folder to the add-on folder. Part B: 3. Edit the add-on folder scripts so it will recognize the new teddy bear files. ----- Editing Files Part A (Teddy Bear Files) First, lets do something easy, I would like you to navigate to your Teddy Bear Mod folder, in there you should find a "bear.png", copy and paste the file to R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Images\Q=Tex032M\Luder\GUI This file is the texture file for the icon when you select it in the game. (NOTE: Normally there is not an icon provided, you have to create your own. Simply take a picture and size it to 128x128 pixels) Now, go to your ... \Teddy Bear Mod\TheGame.AA3.CuddlyTeddy\Images\Q=Tex032M\Shared\Item ...and copy and paste the tool_dildo07.png (this is the texture for the teddy bear mesh) into the following location in the add-on folder: \R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Images\Q=Tex032M\Shared\Item Rename the tool_dildo07.png to tool_teddybear.png Shown in picture below: Note that we do not need a corresponding .txf file because all texture files are by default treated as 100% Opaque and the Teddy Bear does not need any transparency settings. You are now finished with the texture files. Next, lets go to our recently decoded tool07.bs inside the teddy bear mod>scenes>shared>item folder. Right Click tool07.bs and go to "Open With..." and choose either: Open it with NotePad or WordPad or "Choose Default Program" and in the list choose either notepad or wordpad. (Check "always use the selected program to open this kind of file" so you don't have to do this in the future) After that, simply double click the tool07.bs file and you should get something like this the picture below. Next, go to Edit>Replace or Press CTRL + H. Enter "tool07" in the Find what box, and enter teddybear in the Replace with box. Click Replace All Repeat the process but this time enter "dildo07" in the Find what box and enter teddybear in the Replace with box. Click Replace All again. When you are done, go to file>save then exit the notepad. Copy and Paste the edited tool07.bs file into \R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Scenes\Shared\Item. Next right click the tool07.bs and Rename it to "tool_teddybear" (do not mess with the .bs leave that as is). Now take the BSB Tool and encode the tool_teddybear.bs so it becomes tool_teddybear.bsb. Picture Shown Below: Good, you are now finished with the Teddy Bear Mod folder. Before we move on lets summerize what we just did: #We moved the teddy bear icon texture file into the add-on icon-texture folder. #We moved the teddy bear mesh texture file into the add-on mesh-texture folder. #We Edited and Moved the teddy bear mesh file into the add-on mesh folder Editing Files Part B (Add-On Script files) We are now going to go edit the .bsb files in the Add-On folder's "Script" folder. Navigate to: R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Scripts\Luder\Item and open the AcTool30301.bs file that you decoded previously. Change 30301 to 31000 and zhair01 to teddybear. (Note: that the number is an arbitary number choosen because it has not been used, there is no significance in 31000) You want to change the zhair01 to teddybear because that is what we named our mesh under shared>item>tool_teddybear. Note: As you progress through this section you should start to see a pattern and things will make more sense. After you change the values, go to file>save. Rename AcTool30301.bs to AcTool31000.bs. Use the BSB Tool to encode AcTool31000.bs so it becomes AcTool31000.bsb Next, navigate to \R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Scripts\Shared\GUI Open the IconCollection_T1addonTools.bs '''file. Scroll to the bottom, and do what the picture shows below: Becareful with the ""{" brackets make sure that your edits are exactly like the right part of the picture. At this point you should have a faint idea of what just happened: We added a few lines of code to indicate a new object (teddy bear) as well as telling the game where the ICON for the teddy bear is (in GUI/bear.png) As always, when your done, go to File>Save. Use BSB Tool to encode the IconCollection_T1addonTools.bs file so it becomes a IconCollection_T1addonTools.[bsb file. Now go to R9AddOnTools1_v1.5\TheGame.020.R9AddOnTools1\Scripts\Shared\Common You should have three bs files here: #TcToolsAttributesT1Addon.bs #TcToolsT1Addon.bs #TcToolsT1Addon.L=EN.bs Lets open up #1, TcToolsAttributesT1Addon.bs first, scroll to the bottom and follow the instructions below: When you are done, go to file>save. Use the BSB Tool to encode the file. Next, lets open #2 or TcToolsT1Addon.bs, copy the highlighted part shown in the picture (left) below, scroll down to the bottom, CTRL + V to paste the highlighted part. Then change the values 30301 to 31000. Your end result should look like the picture on the right. When you are done, go to File>Save. Encode the file using BSB Tools. Now lets open up #3 TcToolsT1Addon.L=EN.bs. and follow the instructions below: When you are done. Go to file>save. Encode the .bs file with BSB tools. '''Last but not least, use the txx tool, use "select directory" and select the TheGame.020.R9AddOnTools1 folder and click encode. You should now end up with a TheGame.020.R9AddOnTools1.txx Stick the txx file into your \TheGame\Archives\2.114.001 folder. Launch the game. In Go to Pose Editor, go to connect toy, choose "free" and you should end up with the following screen: ' Congratulations, you have learned the basics to adding new objects to add-ons!' Tips and Hints F.A.Q.s Common Errors and Mistakes: *Did you make sure you saved the .bs file after you made changes to it? *Did you make sure you encode the .bs file after you made changes to it? Sometimes an error can be caused by something as simple as a missed bracket "[ or {" so becareful and make sure you are doing things correctly. If you mess up and don't remember how to get back to the original file settings, you can always re-download the add-on file in the link given above.